Skip to main content
Version: Next

App Provider

Traceability kit banner

The following page offers specific developer resources, including payloads and API endpoints for data consumer and app provider. It is important to read the business and architecture view first to understand everything.

Quality Notifications​

The traceability app providers are supposed to implement the capabilities to enable the standardized exchange of information on quality notifications in Catena-X network (Quality Alert and Quality Investigation). Quality investigations refer to sending standardized notifications to direct suppliers (top-down) while Quality Alerts refer to sending notifications to direct customers (bottom-up). This allows supply chain stakeholders to promptly transmit quality notifications to their immediate business partners, in instances where quality issues pertain to supplied products or impact already manufactured items incorporating the defective component, until the root of the problem or affected end-products are determined. This feature will enable the whole industry to exchange and act upon quality issues in a more standardized, integrated, accelerated and precise manner in order to streamline claim management, avoid general and inaccurate recalls as well as reduce cost and safeguard brand reputation.

In order to uniquely reference the affected parts across the network in the context of a quality incident, the exchange of quality notifications uses Catena-X Unique ID, which are the network-wide unique identifiers for a serialized part or batch, for which a digital twin has been created. Therefore, an app provider should also deliver capabilities for standardized creation of digital twins of vehicles, parts and materials as described in the Industry Core KIT and Digital Twin KIT.

Quality Notifications

Quality Notification Process​

The notification process takes place between traceability applications or application stacks, and the focus is on minimal interaction, which must be supported by all applications participating in a quality notification or quality investigation scenario. This minimal interaction includes sending and receiving of quality notification as well as updating of the notification state. Application internals like user journeys, process steps or workflows for notification creation and management in an application are not standardized within Catena-X, and therefore omitted.

The notification states and their cycle are described in the following figure. Notification State Model

Quality Notification API​

A standardized set of APIs and payloads are specified to enable partners to send quality notifications in a standardized way while already knowing which parts (i.e., serialized parts or batches) and which direct customers or suppliers are affected. Notifications are - in contrast to classical data offers in Catena-X which is created for consumption by external stakeholders - a way to push notification related data from a sender to a receiver. For now, this notification API is limited to the sending and receiving of quality notifications as well as the update of the notification status following a state model. It is important to mention that the notification API shall be implemented into each participant's traceability solution or solution stack in order to be able to receive information related to quality issues. The implemented endpoints shall be able to process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. Meanwhile, this notification API shall only be accessible after successful contract negotiation via Connector based on Dataspace Protocol (DSP), since the API is made available as part of an EDC data asset with usage policy attached. Please refer to the corresponding Notification API specifications for more details:

✋ For the current release, version 1.2.1 is mandatory and must be supported by every App provider. The newer version 2.0.0 can be supported optionally.

Block Notifications​

While quality notifications are primarily aimed at (first) contact between business partners, block notifications represent an extended form of data exchange in order to actively initiate an immediate measure to block or sort out the produced parts at the customer's production or logistics. As the quality notifications, block notifications take place between traceability applications or other application stacks, so that this functionality must be implemented by both business partners application.

In this case, block notifications include a notification status similar to quality notifications to track communication, but also include a new status model for each individual part of the block notification to provide additional information. For example, whether the part was blocked or whether the process to block a part was canceled.

✋ Since the Catena-x unique ID is used for the individually listed (damaged) parts in the block notification, the app provider should also provide functions for the standardized creation of digital twins of vehicles, parts and materials, as already mentioned in the quality notifications section.

Block Status Model​

In order to track the blocking process in the Catena X network, a defined status model is used for each part of the block notification: Block Status Model

  • ACTIVE means that the part has been identified as a damaged and safety-critical part and must therefore be blocked on the customer side.
  • PART_BLOCKED is used when the recipient has received the block notification and actually blocks / sorts out the damaged parts as a measure.
  • CANCELED serves as the update status of the component originally identified to be blocked if the supplier subsequently determines that the original part does meet safety requirements, is not damaged or that the information was sent by mistake. This status can also be set by the manufacturer if, after an (initial) analysis, the part does not require a block.

Block Notification API​

A standardized API and corresponding payloads are specified for block notification to enable and ensure the exchange of information that is critical to the blocking process in a standardized way. At this point, the notification API is focused on sending and receiving notifications with a full stack of block information and on updating a previously sent notification by changing the block status. The implemented endpoints shall be able to process the defined request body and respond with the HTTP status codes and - if required - reply with the defined response body. Meanwhile, the Block Notification API shall only be accessible after successful contract negotiation via Connector based on Dataspace Protocol (DSP), since the API is made available as part of an EDC data asset with usage policy attached. Please refer to the corresponding Block Notification API specification for more details:

✋ For the current release, version 1.0.0 is optional and MUST be supported by every App provider from the next (major) release. The block notifications are not standardized yet, but will be released as a new optional functionality in the CX-0125 Traceability Use Case Standard as of the next release 25.03.

Asset Registration via Connector​

Since the notification APIs are published towards the network using a data asset/contract definition in terms of the dataspace protocol (DSP), there are general guidelines defined for registering a notification receiving endpoint within a data asset. The traceability solutions are supposed to implement a similar data asset with the same structure and provisioning towards Catena-X. It is important to mention that it could be possible that more than one notification endpoint needs to be made available in parallel towards the network in order to support the versioning and compatibility strategy in the Catena-X ecosystem.

Asset Creation​

The notification endpoint providers must set properties dct:type and cx-common:version which are used to classify the asset so that partner app providers are able to filter the right assets.

In general, during EDC asset creation, the notification API version needs to provided for cx-common:version as specified in OpenAPI documentation. For dct:type the following asset typizations should be used during implementation:

  • ReceiveQualityInvestigationNotification
  • UpdateQualityInvestigationNotification
  • ReceiveQualityAlertNotification
  • UpdateQualityAlertNotification
  • ReceiveBlockNotification
  • UpdateBlockNotification

Please refer to the Digital Twin KIT for more details.

Example Payload for Asset Creation:

{
  "@context": {
    "edc": "https://w3id.org/edc/v0.0.1/ns/",
    "cx-common": "https://w3id.org/catenax/ontology/common#",
    "cx-taxo": "https://w3id.org/catenax/taxonomy#",
    "dct": "https://purl.org/dc/terms/"
  },
  "@id": "{{ _.edcAssetId }}",
  "properties": {
    "dct:type": {
      "@id": "cx-taxo:ReceiveQualityInvestigationNotification"
    },
    "cx-common:version": "1.2",
  },
  "privateProperties": {
  },
  "dataAddress": {
    "@type": "DataAddress",
    "type": "HttpData",
    "baseUrl": "{{ _.url_backend }}",
    "proxyQueryParams": "true",
    "proxyPath": "true",
    "proxyMethod": "false",
    "oauth2:tokenUrl": "{{ _.url_keycl_backend }}",
    "oauth2:clientId": "{{ _.client_id_backend }}",
    "oauth2:clientSecretKey": "{{ _.sec_name_vault }}"
  }
}

Policy Creation​

For general guidelines for policy creation, please refer to Industry Core KIT and Connector KIT. It is possible to restrict visibility of data offer for notification API with access policy either for members of Catena-X (“Membership”) and one or several Data Consumers identified by a specific business partner number ("BusinessPartnerNumber"). As for usage policy, participants and related services must restrict the data usage for notification endpoints by using the following policy rules:

  • Data Exchange Governance (leftOperand: “FrameworkAgreement”) – The official "Data Exchange Governance" is published on Catena-X website
  • at least one use case purpose (“UsagePurpose”) from the ODRL policy repository
    • for quality notifications, the corresponding usage policy MUST be used (leftOperand: “qualityNotifications”)
    • for block notifications, the same usage policy as quality notifications MUST be used (leftOperand: “qualityNotifications”)

Additionally, respective usage policies MAY include the following policy rule:

  • Reference Contract (“ContractReference”).

Example Payloads for Policy Creation:

{
  "@context": {
    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
   },
   "@id": "<POLICY-ID>",
   "policy": {
     "@context": [
       "http://www.w3.org/ns/odrl.jsonld",
         {
           "cx-policy": "https://w3id.org/catenax/policy/"
         }
      ],
        "@type": "Set",
        "profile": "cx-policy:profile2405",
        "permission": [
      {
      "action": "use",
        "constraint": {
          "and": [
            {
              "leftOperand": "cx-policy:FrameworkAgreement",
              "operator": "eq",
              "rightOperand": "DataExchangeGovernance:1.0"
            },
            {
              "leftOperand": "cx-policy:UsagePurpose",
              "operator": "eq",
              "rightOperand": "cx.core.qualityNotifications:1"
            }
          ]
        }
      }
    ]
  }
}

Asset Consumption via Connector​

Versioning​

The notification sender as well as a requestor of an asset must be able to handle multiple assets for this endpoint, being differentiated only by the version (cx-common:version) and should choose the asset with the highest compatible version number implemented by themselves. If the requestor cannot find a compatible version with their own, the requestor must not initiate contract negotiation.

Policy Check​

Meanwhile, the requesting application must be able to validate whether the attached policy constraints (see section Policy Creation above) in the data assets follow company-defined rules and regulations, while selecting the appropriate offer. If no data offer is compliant with company rules for a queried data asset, the requestor must terminate the data transfer.

NOTICE​

This work is licensed under the CC-BY-4.0.

  • SPDX-License-Identifier: CC-BY-4.0
  • SPDX-FileCopyrightText: 2023 BASF SE
  • SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
  • SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML)
  • SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG
  • SPDX-FileCopyrightText: 2023 Mercedes Benz AG
  • SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH
  • SPDX-FileCopyrightText: 2023 SAP SE
  • SPDX-FileCopyrightText: 2023 Siemens AG
  • SPDX-FileCopyrightText: 2023 T-Systems International GmbH
  • SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG
  • SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation
  • Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Traceability%20Kit (latest version)